home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / djgpp / tktdoc / dvxhelp.doc < prev    next >
Encoding:
Text File  |  1994-08-11  |  36.5 KB  |  1,317 lines

  1. DESQVIEW/X HELP PROGRAMMING REFERENCE
  2.  
  3. The DESQview/X Help System is a general mechanism for providing on-line
  4. help services to applications.  The basic metaphor is a wire bound
  5. "flip" reference with topics organized into sections.  This
  6. widely recognized metaphor provides more information than a reference
  7. card in a more concise presentation than a user manual.
  8.  
  9. The help notebook contains tabs along its lower edge that allow a
  10. user to "turn" to the beginning of a particular section, and
  11. navigation buttons down the right hand side. The notebook displays
  12. as much of a topic as possible and lists the number of pages in the
  13. topic as well as the topic number along its lower edge. The text of
  14. a topic may be accented by changes in font and color, and may contain
  15. pictures (or "icons"). In addition, the text may contain "hypertext"
  16. links whereupon if a user clicks with the mouse on a word(s), the
  17. notebook automatically jumps to a new topic. This "jump text"
  18. is usually highlighted in a different color to distinguish it from
  19. regular text. The buttons to the right allow a user to "backtrack"
  20. through a notebook (after clicking on jump text and/or section tabs),
  21. display the previous or next topic, display the previous or next page
  22. of a topic (paging up and down) as well as being able to close the
  23. notebook ("exit").
  24.  
  25. Help System Components
  26.  
  27. The DESQview/X Help System consists of the following three components:
  28.  
  29. A Help File
  30.  
  31. This is a single file that contains all of the notebook's
  32. text and pictures, instructions for moving around the notebook (jump
  33. instructions) as well as specifying the section tabs, colors, etc.
  34.  
  35. The DESQview/X
  36.  
  37. Help Engine
  38.  
  39. This is the application that reads the help file, creates
  40. the notebook on the display screen and responds to user input.
  41.  
  42. Help Interface
  43.  
  44. Routines
  45.  
  46. These routines are used by an application to instruct
  47. the Help engine to display help. They transparently handle the starting
  48. of the Help engine and the communication that occurs between the Help
  49. engine and the application.  In addition, a stand alone version of
  50. these routines are provided in the form of the DISPHELP
  51. program which can be used from the command line or in a .DVP file
  52. to display a help notebook.
  53.  
  54. This chapter first discusses how to create a Help file and is followed
  55. by details on using the help interface routines and the DISPHELP
  56. program.
  57.  
  58. Creating Help Files
  59.  
  60. A DESQview/X Help file begins life as a collection of files, one file
  61. for each topic in the notebook. In addition, there may be some additional
  62. files, such as .XPM files, that are used to create pictures within
  63. a topic as well as topic files that do not appear on their own, but
  64. are "included" by other topics such that they act like "subroutines".
  65.  
  66. All of these files are combined into one file by using the HELPLIB
  67. program, included in this package. This process may be automated through
  68. the use of HELPLIB response files to save the tedium
  69. of specifying the same files to HELPLIB every time
  70. a help file is created.
  71.  
  72. Topic files consist of ASCII text interspersed with
  73. special help commands (or "escape" sequences) that affect
  74. such things as a change in font or the defining of some jump text
  75. and the jump destination.
  76.  
  77. Picture files are .XPM files created with a utility
  78. such as the DESQview/X Icon Editor.
  79.  
  80. When combining files into a single help file using HELPLIB,
  81. the ordering of the files is of great importance. A typical help file
  82. consists of the following constituent files in this order:
  83.  
  84. frcover
  85. topic1
  86. topic2
  87.  
  88. :
  89.  
  90. topicxx
  91. bkcover
  92. include1
  93. include2
  94. include3
  95.  
  96. :
  97.  
  98. xpm1
  99. xpm2
  100. xpm3
  101.  
  102. frcover must be included and defines the cover of the notebook. It
  103. should be first in the help file.
  104.  
  105. topic1,topic2,topic3 ... These files (which may use any
  106. names that you choose) are the notebook's regular displayable topics.
  107. When a user pages through the notebook, the topics are displayed in
  108. the order that their files appear in the help file.
  109.  
  110. bkcover must be included and defines the section tabs that appear
  111. along the bottom of the notebook.
  112.  
  113. In addition, bkcover defines the end of the regular displayable topics.
  114.  
  115. include1,include2,include3 ... These files (which may
  116. use any names that you choose) appear after the bkcover
  117. file and are topics which are included by the regular topics (they
  118. act like subroutines). Since they are not stand alone topics and should
  119. not be displayed by themselves, they appear after bkcover.
  120.  
  121. xpm1,xpm2,xpm3 ... These files (which may use any names
  122. that you choose) appear after the bkcover
  123. file and are picture files (.XPMs) which are used by both the regular
  124. topics and the included topics. Since they should not be displayed
  125. by themselves, they appear after bkcover.
  126.  
  127. Topic Files
  128.  
  129. Topic files (that includes frcover and bkcover) consist of
  130. paragraphs of text interspersed with help commands:
  131.  
  132. A paragraph
  133.  
  134. A paragraph of text is defined as a string of ASCII characters
  135. that end with a <CR> (carriage return,line feed). The <CR>
  136. is used to signal the end of the paragraph and will be output when
  137. displaying the notebook text.
  138.  
  139. Help commands
  140.  
  141. Help commands begin with a slash character / followed
  142. by a one or two letter mnemonic. If you wish the slash character to
  143. appear in the notebook text, a double slash // is used.
  144.  
  145. An example of a topic file might be:
  146.  
  147. /FH/UMoving between Application Manager Windows/U/FB<CR>
  148.  
  149. <CR>
  150.  
  151. To switch from one Application Manger window to another (that is make
  152. another window "current"):<CR>
  153.  
  154. <CR>
  155.  
  156. /ILmouse.xpm/Click with Button
  157. 1 on the border of the window you want to switch to.<CR>
  158.  
  159. This topic consists of five paragraphs (three lines of text with two
  160. blank lines in between, each terminated by a <CR>). In addition,
  161. the help commands, /FH, /U, /FB, /IL are used. A full list of help
  162. commands is presented later.
  163.  
  164. FRCOVER
  165.  
  166. Frcover is a topic file that defines the text that appears on the
  167. cover of the notebook.
  168.  
  169. An example might be:
  170.  
  171. /FTApplication
  172. Manager<CR>
  173.  
  174. /FS(c) 1990-1992 Quarterdeck
  175. Office Systems<CR>
  176.  
  177. This directs the Help engine to:
  178.  
  179. Set the font to the Cover Title font (/FT).
  180.  
  181. Output "Application Manager".
  182.  
  183. Output a <CR> to begin a new line.
  184.  
  185. Set the font to the Cover Subtitle font (/FS).
  186.  
  187. Output "(c) 1990-1992 Quarterdeck Office Systems".
  188.  
  189. Output a <CR> to begin a new line.
  190.  
  191. BKCOVER
  192.  
  193. Bkcover is a topic file that defines the section tabs that appear
  194. at the bottom of the notebook. Section tabs must be defined with the
  195. jump command /JB. In addition,
  196. use of the /CT command enables you to
  197. define the colors of the tabs and the /IC
  198. command can be used to specify a picture file (.XPM) that will be
  199. used to create the notebook's cover.
  200.  
  201. An example might be:
  202.  
  203. /ICcover.xpm/<CR>
  204. /CTPcBrightGreen/<CR>
  205. /JBContents/contents/<CR>
  206. /CTPcYellow/<CR>
  207. /JBOverview/overview/<CR>
  208. /CTPcBrightMagenta/<CR>
  209. /JBCommands/details/<CR>
  210.  
  211. This directs the Help engine to:
  212.  
  213. Set the cover's background to cover.xpm, a picture
  214. file that appears in the help file after bkcover
  215. (/IC).
  216.  
  217. Set the current tab color to PcBrightGreen, a DESQview/Xcolor
  218. name from RGB.TXT (/CT).
  219.  
  220. Create a jump using the text "Contents" (this
  221. will appear on the section tab) that will go to the topic with the
  222. filename of 'contents' (/JB).
  223. This topic file is a regular displayable topic that appears between
  224. the frcover and bkcover
  225. files in the help file. The extra slashes / in this line define the
  226. end of the text to be output and the end of the topic filename that
  227. a user will jump to.
  228.  
  229. Set the current tab color to PcYellow.
  230.  
  231. Create a jump (i.e. tab) with the text "Overview"
  232. that jumps to the topic with the filename of 'overview'.
  233.  
  234. Set the current tab color to PcBrightMagenta.
  235.  
  236. Create a jump (i.e. tab) with the text "Details"
  237. that jumps to the topic with the filename of 'details'.
  238.  
  239. Help Commands
  240.  
  241. Help commands are split into the following categories: alignment,
  242. appearance, picture, utility and bkcover:
  243.  
  244. Alignment
  245.  
  246. Alignment commands affect the alignment of the paragraph
  247. they are attached to.
  248.  
  249. Appearance
  250.  
  251. Appearance commands change the appearance of text (fonts,
  252. underlining, color).
  253.  
  254. Picture
  255.  
  256. Picture commands display picture (.XPM) files.
  257.  
  258. Utility
  259.  
  260. Utility commands perform jumps (hypertext links) and
  261. display 'include' topics.
  262.  
  263. Bkcover
  264.  
  265. Bkcover commands are special commands that may only be
  266. used in the bkcover file.
  267.  
  268. Alignment Commands
  269.  
  270. Alignment commands affect the alignment of the paragraph they are
  271. attached to. It is very important to note that these commands affect
  272. the whole of a paragraph no matter where they appear in that paragraph--
  273. whether at the beginning or right at the end, immediately before the
  274. <CR>.
  275.  
  276.  /AL
  277.  
  278.  /AC
  279.  
  280.  /AR
  281.  
  282. These commands set the general alignment of the paragraph. They perform
  283. the following:
  284.  
  285. /AL
  286.  
  287. Align paragraph to the left edge of the notebook (left
  288. justified).
  289.  
  290. /AC
  291.  
  292. Center paragraph in the middle of the notebook (centered).
  293.  
  294. /AR
  295.  
  296. Align text to the right edge of the notebook (right justified).
  297.  
  298. Example:
  299.  
  300. /ACImportant
  301. Note<CR>
  302.  
  303. <CR>
  304.  
  305. /ALNote that ...<CR>
  306.  
  307. This example centers the first line and left justifies the third.
  308.  
  309.  /ML[+ | -]#/
  310.  
  311. This command sets the left margin. If the + or - characters are not
  312. used, then the margin setting is absolute. If they are specified,
  313. this command produces a relative change.
  314.  
  315. #, a decimal number that represents the number of quarter
  316. widths of the current font. A quarter width is the width of a typical
  317. character in the current font divided by 4.
  318.  
  319. +, (optional) the margin setting should increase by the
  320. quarter widths specified.
  321.  
  322. -, (optional) the margin setting should decrease by the
  323. quarter widths specified.
  324.  
  325. Once this command has been executed, the margin setting remains in
  326. effect for all following paragraphs until changed again with another
  327. /ML command.
  328.  
  329. Example:
  330.  
  331. /ML+4/Indented
  332. Text.<CR>
  333.  
  334. /ML-4/Regular Text.<CR>
  335.  
  336. This example indents the text "Indented Text." by 4 quarter
  337. widths.
  338.  
  339.  /MR[+ | -]#/
  340.  
  341. This command sets the right margin. If the + or - characters are not
  342. used, then the margin setting is absolute. If they are specified,
  343. this command produces a relative change.
  344.  
  345. #, a decimal number that represents the number of quarter
  346. widths of the current font. A quarter width is the width of a typical
  347. character in the current font divided by 4.
  348.  
  349. +, (optional) the margin setting should increase by the
  350. quarter widths specified.
  351.  
  352. -, (optional) the margin setting should decrease by the
  353. quarter widths specified.
  354.  
  355. Once this command has been executed, the margin setting remains in
  356. effect for all following paragraphs until changed again with another
  357. /MR command.
  358.  
  359. Example:
  360.  
  361. /AR/MR+4/Indented Text.<CR>
  362.  
  363. /ML-4/Regular Text.<CR>
  364.  
  365. This example justifies the text to the right margin and indents the
  366. text "Indented Text." by 4 quarter widths.
  367.  
  368.  /HI[+ | -]#/
  369.  
  370. This command defines a hanging indent.
  371.  
  372. The first line of a paragraph is never affected by this command, but
  373. all following lines are. This command specifies the indent of those
  374. lines from where the first line of the paragraph appears. If a positive
  375. setting is used, the lines will appear to the right of the first line.
  376. If a negative value is used they will appear to the left of the first
  377. line, but never further than the left margin of the notebook. This
  378. can be used to create a paragraph whereby the first line appears 'indented'
  379. or 'outdented'.
  380.  
  381. #, a decimal number that represents the number of quarter
  382. widths of the current font. A quarter width is the width of a typical
  383. character in the current font divided by 4.
  384.  
  385. +, (optional) the hanging indent setting displays subsequent
  386. lines indented to the right of the first line.
  387.  
  388. -, (optional) the hanging indent setting displays subsequent
  389. lines indented to the left of the first line.
  390.  
  391. Once this command has been executed, the setting remains in effect
  392. for all following paragraphs until changed again with another /HI or the /HC
  393. command.
  394.  
  395. Example:
  396.  
  397. /AL/ML4//HI-4/Xxxxx
  398. xxxxx xxxxx ..... xxxxx xxxxx xxxxx<CR>
  399.  
  400. /HC/ML0/<CR>
  401.  
  402. This example sets the left margin to 4 quarter widths and then sets
  403. the hanging indent to -4 quarter widths producing this effect:
  404.  
  405.       Xxxxx xxxxx xxxxx
  406.  
  407. xxxxx xxxxx xxxxx xxxxx
  408.  
  409. xxxxx xxxxx xxxxx xxxxx
  410.  
  411.  /HC
  412.  
  413. This command clears any hanging indent.
  414.  
  415.  
  416.  
  417. Appearance Commands
  418.  
  419. Appearance commands change the appearance of text (fonts, underlining,
  420. color). They take affect wherever they appear in a paragraph.
  421.  
  422.  /FT
  423.  
  424.  /FS
  425.  
  426.  /FH
  427.  
  428.  /FL
  429.  
  430.  /FB
  431.  
  432.  /FN
  433.  
  434. These commands change the font of the text to one of six fonts (that
  435. are chosen by the user through use of the DESQview/X Help configuration
  436. file, DVXHELP.CFG). Hence these commands are meta definitions and
  437. their definitions are as follows:
  438.  
  439. /FT
  440.  
  441. Cover Title font.
  442.  
  443. /FS
  444.  
  445. Cover Subtitle font.
  446.  
  447. /FH
  448.  
  449. Heading font.
  450.  
  451. /FL
  452.  
  453. Label font.
  454.  
  455. /FB
  456.  
  457. Body font (default).
  458.  
  459. /FN
  460.  
  461. Note font.
  462.  
  463. Example:
  464.  
  465. /FHA Big Heading<CR>
  466.  
  467. /FLA Label/FB - and the body of the text.<CR>
  468.  
  469. This produces two lines, the first in the Heading font, the second
  470. line beginning with the Label font, but also using the Body font.
  471.  
  472.  /CN
  473.  
  474.  /CH
  475.  
  476. These commands set the color of the text to one of two colors (that
  477. are chosen by the user through use of the DESQview/X Help configuration
  478. file, DVXHELP.CFG). Hence these commands are meta definitions and
  479. their definitions are as follows:
  480.  
  481. /CN
  482.  
  483. Normal color (default).
  484.  
  485. /CH
  486.  
  487. Highlighted color.
  488.  
  489. Note that a third color is also used for jump text (see the /JB command).
  490.  
  491. Example:
  492.  
  493. Something of special /CHimportance/CN to note.<CR>
  494.  
  495. This example highlights the word "importance".
  496.  
  497.  /U
  498.  
  499. This command toggles underlining on and off.
  500.  
  501. Example:
  502.  
  503. This /Uword/U is underlined.<CR>
  504.  
  505. This example underlines the word "word".
  506.  
  507. Picture Commands
  508.  
  509. Picture commands display picture (.XPM) files.
  510.  
  511.  /ILxpmname/
  512.  
  513. This command defines a picture (icon) that is displayed at the left
  514. margin. Any text following the picture flows to the right of the picture
  515. and only returns to the left edge when the following two conditions
  516. are met: a) the picture ends, and b) a new paragraph begins. These
  517. conditions produce the effect that a single paragraph next to a picture
  518. is indented for the entire length of the paragraph no matter which
  519. one ends first.
  520.  
  521. xpmname is the file name of a .XPM file that appears in
  522. the help file after the bkcover topic.
  523.  
  524. Example:
  525.  
  526. /ILmouse.xpm/Click
  527. with Button 1 on the border of the window you want to switch to.<CR>
  528.  
  529. This example produces a mouse icon to the left with descriptive text
  530. to the right.
  531.  
  532.  /IRxpmname/
  533.  
  534. This command defines a picture (icon) that is displayed at the right
  535. margin. Any text following this command flows up to the left of the
  536. picture and will flow to the right edge when the picture ends.
  537.  
  538. xpmname is the file name of a .XPM file that appears in
  539. the help file after the bkcover topic.
  540.  
  541. Example:
  542.  
  543. /AR/IRmouse.xpm/Click with Button 1 on the
  544. border of the window you want to switch to.<CR>
  545.  
  546. This example produces a mouse icon to the right with descriptive text
  547. to the left (though, right justified).
  548.  
  549.  /IExpmname/
  550.  
  551. This command defines a picture (icon) that is embedded within a line
  552. of text. This command can be used to define characters that do not
  553. appear within a font's character set.
  554.  
  555. Note that if an embedded icon is larger than the height of the line,
  556. the current line height is increased to accommodate the icon.
  557.  
  558. xpmname is the file name of a .XPM file that appears in
  559. the help file after the bkcover topic.
  560.  
  561. Example:
  562.  
  563. Press the Enter /IEenter.xpm/
  564. key.<CR>
  565.  
  566. This example inserts an enter character in the middle of a sentence.
  567.  
  568. Utility Commands
  569.  
  570. Utility commands perform jumps (hypertext links) and display 'include'
  571. topics.
  572.  
  573.  /JBtext/topicname/
  574.  
  575. This command defines both the highlighted text of a jump as well as
  576. its destination topic, creating a "hyperlink" in the notebook.
  577. This command is also used in the bkcover
  578. topic to define section tabs.
  579.  
  580. text, the text to be displayed in the special jump text
  581. color.
  582.  
  583. topicname, the file name of the topic to jump to. This
  584. topic should be a regular displayable topic whose file is listed between
  585. the frcover and bkcover
  586. files in the help file.
  587.  
  588. Example:
  589.  
  590. /FL/JBClick here to go to Contents/contents//FB<CR>
  591.  
  592. This example outputs the text "Click here to go to Contents"
  593. in the Label font, highlights it with the jump color and will transfer
  594. the user to the 'contents' topic if selected.
  595.  
  596.  /Ttopicname/
  597.  
  598. This command includes the referenced topic's contents at the current
  599. position in the current topic. This is useful in sharing common
  600. text/information between many topics. This command may be nested,
  601. such that an included topic may use this command to include another topic.
  602.  
  603. Note that the current margins, paragraph alignment settings, etc.,
  604. are forced onto the included topic. It is advised that topics should
  605. be included on paragraph boundaries for predictable results. Care
  606. should be used to avoid excessive depth as well as circular inclusions.
  607.  
  608. topicname, the file name of the topic to include. It is
  609. recommended that this topic should be an include topic whose file
  610. is listed after the bkcover file in the
  611. help file.
  612.  
  613. Example:
  614.  
  615. The error messages include:<CR>
  616.  
  617. <CR>
  618.  
  619. /Terrors/<CR>
  620.  
  621. This example includes the topic with the file name 'errors' at the
  622. point specified.
  623.  
  624. Bkcover Commands
  625.  
  626. Bkcover commands are special commands that may only be used in the
  627. bkcover file.
  628.  
  629.  /ICxpmname/
  630.  
  631. This command sets the picture (.XPM) file that should be used on the
  632. cover of the notebook.
  633.  
  634. xpmname is the file name of a .XPM file that appears in
  635. the help file after the bkcover topic.
  636.  
  637. Note that this command overrides the /CC command if one is specified.
  638.  
  639. Example:
  640.  
  641. /ICcover.xpm/
  642.  
  643. This example sets the cover picture to 'cover.xpm'.
  644.  
  645.  /CCcolorname/
  646.  
  647. This command sets the color for the cover of the notebook.
  648.  
  649. colorname, this is either a valid DESQview/X colorname
  650. from the RGB.TXT file, or an RGB color definition, containing 1, 2,
  651. 3 or 4 hexadecimal values each for red,green and blue (e.g. #AAA,
  652. #A0A0A0, #A00A00A00, #A000A000A000).
  653.  
  654. Note that this command is overridden by the /IC
  655. command if one is specified.
  656.  
  657. Example:
  658.  
  659. /CCPcGreen/
  660.  
  661. This example sets the cover color to 'PcGreen'.
  662.  
  663.  /CTcolorname/
  664.  
  665. This command sets the color for any tabs defined after the command.
  666.  
  667. colorname, this is either a valid DESQview/X colorname
  668. from the RGB.TXT file, or an RGB color definition, containing 1. 2.
  669. 3 or 4 hexadecimal values each for red,green and blue (e.g. #AAA,
  670. #A0A0A0, #A00A00A00, #A000A000A000).
  671.  
  672. This command remains in effect until changed by another definition.
  673.  
  674. Example:
  675.  
  676. /CTPcBrightGreen/<CR>
  677.  
  678. /JBContents/contents/<CR>
  679.  
  680. /CTPcYellow/<CR>
  681.  
  682. /JBOverview/overview/<CR>
  683.  
  684. This example defines two tabs, the first tab being PcBrightGreen and
  685. the second being PcYellow.
  686.  
  687. Help File Structure
  688.  
  689. It is recommended that help files for applications follow this structure:
  690.  
  691. Contents
  692.  
  693. A section containing the contents of the notebook with
  694. jumps into the notebook.
  695.  
  696. Overview
  697.  
  698. A general overview of the application and how to navigate
  699. within it.
  700.  
  701. Commands
  702.  
  703. Help for all of the commands available in the application.
  704.  
  705. Dialogs
  706.  
  707. Help for all of the dialogs that the application displays.
  708.  
  709. Errors
  710.  
  711. Help for the individual error messages the application
  712. issues.
  713.  
  714. Naturally, you may wish to extend or customize this suggestion to
  715. your own particular needs.
  716.  
  717. The files for this structure would probably be listed in this order
  718. (when presented to HELPLIB.EXE in order
  719. to create the help file):
  720.  
  721. frcover         (Front cover)
  722. contents        (Notebook contents)
  723. overview        (Overview contents)
  724. oview1          (Overview first topic)
  725. oview2          (Overview second topic)
  726.  
  727. :
  728.  
  729. commands        (Commands contents)
  730. command1        (First command topic)
  731. command2        (Second command topic)
  732.  
  733. :
  734.  
  735. dialogs         (Dialogs contents)
  736. dialog1         (First dialog topic)
  737. dialog2         (Second dialog topic)
  738.  
  739. :
  740.  
  741. errors          (Error contents)
  742. error1          (First error topic)
  743. error2          (Second error topic)
  744.  
  745. :
  746.  
  747. bkcover         (Back cover)
  748. include1        (Included topics)
  749. include2
  750.  
  751. :
  752.  
  753. xpm1            (Picture files)
  754. xpm2
  755.  
  756. HELPLIB.EXE
  757.  
  758. A utility program, HELPLIB.EXE is provided
  759. to create and update help files. The command line options are as follows:
  760.  
  761.  HELPLIB [libname | @responsefile]
  762.  
  763. libname, the name of an existing library on which to perform
  764. maintenance.
  765.  
  766. responsefile,
  767. the name of a file to read commands from as though they were entered
  768. interactively.
  769.  
  770. If no response file
  771. is specified (i.e. no command line parameter or only a library name),
  772. then HELPLIB.EXE runs interactively
  773. with the following commands available:
  774.  
  775. Add
  776.  
  777. Add a file to the end
  778. of the help file
  779.  
  780. Burst
  781.  
  782. Burst a help file
  783. into its constituent files
  784.  
  785. Change
  786.  
  787. Rename the name of the help file
  788.  
  789. Dir
  790.  
  791. List the files added to the help file
  792.  
  793. Erase
  794.  
  795. Remove a file from the help file
  796.  
  797. Get
  798.  
  799. Copy a constituent file out of the help file
  800.  
  801. Insert
  802.  
  803. Insert a file into
  804. the help file
  805.  
  806. Make
  807.  
  808. Create a new help file
  809.  
  810. Replace
  811.  
  812. Replace a constituent
  813. file in the help file
  814.  
  815. Use
  816.  
  817. Starting using a different help file
  818.  
  819. Quit
  820.  
  821. Return to DOS
  822.  
  823. Note that commands may be entered by first letter only.
  824.  
  825. A response file contains text exactly as it would be entered interactively
  826. with one response per line. An example response file would be:
  827.  
  828. m                       (Make a new file)
  829. newfile.hlp             (name of file)
  830. frcover                 (front cover)
  831. contents                (topic files)
  832. overview
  833. commands
  834. command1
  835. command2
  836. dialogs
  837. errors
  838. bkcover                 (back cover)
  839. include                 (include files)
  840. xpmfile.xpm             (picture files)
  841. exit                    (exit signals end of m command)
  842. q                       (Quit)
  843.  
  844. A good idea is to create a batch file that uses a response file like
  845. the one shown above:
  846.  
  847. MAKEHELP.BAT:
  848.  
  849. del newfile.hlp
  850.  
  851. helplib @newfile.rsp
  852.  
  853. This ensures that the topics are merged into the help file in the
  854. correct order.
  855.  
  856. Example
  857.  
  858. We shall now build an example help file. The X11 Toolkit diskettes
  859. contain the appropriate help example files.
  860.  
  861. First, open a DOS Window and change to the correct directory:
  862.  
  863. Type CD \DVX\QDECK\HELP and press Enter <CR>.
  864.  
  865. Delete the old help file in case one was previously built:
  866.  
  867. Type DEL EXAMPLE.HLP, press Enter <CR> and
  868. ignore any 'File not found' message if one appears.
  869.  
  870. Create the new help file:
  871.  
  872. Type HELPLIB @EXAMPLE.RSP and press
  873. Enter <CR>.
  874.  
  875. Now copy the new help file to the help directory and display it:
  876.  
  877. Type COPY EXAMPLE.HLP \DVX\HELP and press Enter
  878. <CR>.
  879.  
  880. Type DISPHELP -F EXAMPLE.HLP and press
  881. Enter <CR>.
  882.  
  883. It is recommended that you examine the response file EXAMPLE.RSP as
  884. well as the topic files it uses as an example of writing and using
  885. topic files.
  886.  
  887. DESQview/X Help Interface
  888.  
  889. When you have created your DESQview/X Help .HLP file using HELPLIB, 
  890. your program can request that Help display a help notebook at a particular 
  891. topic. (It should be noted that your program need not be an X client--the 
  892. help interface routines do not rely on the X Window System.)
  893.  
  894. To do this requires the use of two files - HELP.H and the DESQview/X System Library. HELP.H is a file that defines error return 
  895. codes and prototypes for the Help interface routines--this file should 
  896. be included into your program code. The DESQview/X System Library, 
  897. SYSTEM.LIB, contains the Help interface 
  898. routines and should be linked in with your program - it can be found 
  899. in the appropriate subdirectory off the \DVX\LIB directory.
  900.  
  901. HELP.H is found in the DESQview/X 
  902. INCLUDE subdirectory, usually \DVX\INCLUDE.
  903.  
  904. The four Help interface routines are:
  905.  
  906. Help_initialize 
  907.  
  908.  
  909. Initialize the help interface
  910.  
  911. Help_get_sections
  912.  
  913. Get the names of the 
  914. notebook's sections (the names on the tabs)
  915.  
  916. Help_show
  917.  
  918. Display the notebook at a particular topic
  919.  
  920. Help_terminate
  921.  
  922. Terminate use of the help interface
  923.  
  924. Typically a program will use the following sequence of calls:
  925.  
  926. Help_initialize(...);
  927.  
  928. :
  929.  
  930. Help_get_sections(...);
  931.  
  932. /* place section names on Help menu */
  933.  
  934. :
  935.  
  936. /* help requested! */
  937.  
  938. Help_show(a_topic);
  939.  
  940. :
  941.  
  942. /* help requested! */
  943.  
  944. Help_show(another_topic);
  945.  
  946. :
  947.  
  948. /* help requested! */
  949.  
  950. Help_show(and_another_topic);
  951.  
  952. :
  953.  
  954. Help_terminate(...);
  955.  
  956. Note that there is no Help_unshow (or similar command)--a user may 
  957. close the help notebook at their discretion or leave it open. Hence 
  958. the notebook operates independently of the application. If the user 
  959. performs an operation in the application which generates another Help_show(...) command and
  960. its notebook is already open, then that notebook will appear (if iconified) 
  961. and is updated to the specified topic.
  962.  
  963. How it Works
  964.  
  965. Understanding how the Help system operates is beneficial in tracking
  966. down problems and using the Help system effectively.
  967.  
  968. The Help system consists of a Help engine running in its own DESQview 
  969. process. This Help engine can accept requests from multiple applications 
  970. concurrently and will create multiple independent notebooks. Even 
  971. though applications can make requests to the Help engine directly,
  972. the help interface routines are provided to simplify that process.
  973.  
  974. Requests are made to the Help engine using the DESQview mailbox API. 
  975. When the Help engine has completed the operation it will return a 
  976. status code to the sender also using the mailbox API.
  977.  
  978. Let us now examine what function each of the help interface routines 
  979. perform:
  980.  
  981.  Help_initialize
  982.  
  983. When called, this routine sets up an "account" that contains 
  984. information that will be sent to the Help system every time a request 
  985. to the Help engine is made. At this point no communication with the 
  986. Help engine (if it is present) is performed.
  987.  
  988.  Help_get_sections
  989.  
  990. This function tries to locate the help file on disk (help files are 
  991. relative to the Help system's directory and not the application's). 
  992. Once the help file is located, the section names (and their corresponding 
  993. topics) are extracted and returned to the calling application.
  994.  
  995. Note that no communication with the Help engine (if it is present) 
  996. is performed.
  997.  
  998.  Help_show
  999.  
  1000. When called, Help_show 
  1001. checks to see if the Help engine is already running. If it is not, 
  1002. Help_show starts 
  1003. the Help engine and waits for it to initialize itself. If there are 
  1004. any problems, Help_show 
  1005. will time out and return an error to the application.
  1006.  
  1007. Once the Help engine is running (or was already running in the first
  1008. place), Help_show
  1009. sends a mail message request to the Help engine. The Help engine performs
  1010. the request and sends back a status mail message to Help_show. If there
  1011. are any problems, Help_show will time out and return an error to the
  1012. application.
  1013.  
  1014.  Help_terminate
  1015.  
  1016. This function sends a message to the Help engine informing it that 
  1017. the "connection" to a particular notebook is being severed 
  1018. and deallocates the account information from local storage.
  1019.  
  1020. Help Callback
  1021.  
  1022. There are times when the help interface routines loop is constantly 
  1023. waiting for something to happen (for example, after starting the Help 
  1024. engine and waiting for it to initialize itself, or after sending it 
  1025. a message and waiting for a reply).
  1026.  
  1027. There can be instances when the help interface routines spend a significant 
  1028. amount of time (a few seconds) in these loops (especially when starting 
  1029. the Help engine).  During this time, if a user uncovers or resizes 
  1030. one of the application's windows, the window will remain blank until 
  1031. the interface routine exits the busy-wait loop.
  1032.  
  1033. To counteract this, the application may specify a callback routine 
  1034. that will be called whenever the help interface routines pass through 
  1035. a loop.  This callback routine may perform useful work such as checking 
  1036. and reacting to Expose or ConfigureNotify events.
  1037.  
  1038. The callback routine MUST be of the form:
  1039.  
  1040. void helpcallback (void *user_arg);
  1041.  
  1042. Help .DVP File
  1043.  
  1044. The help routines specified will use the DVXHELP.DVP 
  1045. in the DESQview/X DVPs directory (normally \DVX\DVPS) to start the 
  1046. Help engine. Any changes to this .DVP may result in problems with 
  1047. the Help system.
  1048.  
  1049. Do not have .DVPs with the same name (DVXHELP.DVP) 
  1050. located in your application directory as this .DVP file will be used 
  1051. instead and may cause problems.
  1052.  
  1053. Help Filenames
  1054.  
  1055. The Help engine typically runs in its own help directory (usually 
  1056. \DVX\HELP) - this is specified by the .DVP file that is used to start 
  1057. the engine (usually \DVX\DVPS\DVXHELP.DVP). Because 
  1058. of this, all requests to the Help engine must contain help file names 
  1059. that are relative to whatever directory the engine is running in.
  1060. This is very important to remember.
  1061.  
  1062.  
  1063.  
  1064. Help Routines
  1065.  
  1066. A description of each of the four interface routines now follows:
  1067.  
  1068.  Help_initialize
  1069.  
  1070. Synopsis
  1071.  
  1072. #include <help.h>
  1073. int Help_initialize
  1074. (char *display_name, char *win_title, char *file_name,
  1075.     int start_timeout, int send_timeout, Help_callback callback,
  1076.     void *user_arg, HelpID *id);
  1077.  
  1078. Description
  1079.  
  1080. Help_initialize
  1081. is used to initialize the help interface routines and must be called
  1082. before any others. It returns a Help ID that is used in subsequent
  1083. calls to save the trouble of specifying the same information (display
  1084. name, help file name, etc.) every time.  This Help id can be thought
  1085. of as a logical "connection" to the Help system.
  1086.  
  1087. If an application wishes to display several different notebook files
  1088. or use several different displays, Help_initialize
  1089. must be called separately for each instance - in each case, a different
  1090. Help id will be returned.
  1091.  
  1092. display_name, the display where the notebook should appear.
  1093. If this parameter is NULL, XDisplayName is used as the display name.
  1094.  
  1095. win_title, the window title of the notebook. If this parameter
  1096. is NULL, "Help!" is used.
  1097.  
  1098. file_name, the name of the help file to be used. NOTE:
  1099. this name should be specified relative to where the Help system
  1100. runs,normally the HELP subdirectory of DESQview/X--\DVX\HELP. If you
  1101. store your help file in this directory (as is recommended), then no
  1102. path is required in the filename. If you store your help file with
  1103. your application, then pass a fully qualified drive:\path\filename
  1104. so that the Help system may locate the file.
  1105.  
  1106. start_timeout, the number of seconds that the help interface
  1107. should wait after starting the Help system (using the specified .DVP)
  1108. and the system initializing itself. If the interface times out (after
  1109. a reasonable number of seconds - 15 or so) a problem has probably
  1110. occurred.
  1111.  
  1112. send_timeout, the number of seconds that the help interface
  1113. should wait after sending a request to the Help system and waiting
  1114. for a reply. If the interface times out (after a reasonable number
  1115. of seconds - 10 or so) a problem has probably occurred.
  1116.  
  1117. callback, the name of a Help callback function that is
  1118. called whenever the help interface is waiting for a reply from the
  1119. Help system. This callback routine can handle Expose/Configure Notify
  1120. events, for example. If this parameter is NULL, then no callback will
  1121. occur.
  1122.  
  1123. user_arg, an argument that is always passed to the specified
  1124. callback function.
  1125.  
  1126. id, <RETURNED> the Help id created for this notebook.
  1127.  
  1128.  Help_get_sections
  1129.  
  1130. Synopsis
  1131.  
  1132. #include <help.h>
  1133. int Help_get_sections(HelpID id, int *ntabs,
  1134.                       char**tabs[], char**topics[]);
  1135.  
  1136. Description
  1137.  
  1138. Help_get_sections
  1139. returns the number of sections and a list of section names (the tabs
  1140. appearing along the bottom of a help notebook). These names may be
  1141. used on a help menu, for example. In addition, the corresponding topic
  1142. names (for use with the Help_show
  1143. function) are also returned.
  1144.  
  1145. id, Help id (returned by Help_initialize).
  1146.  
  1147. ntabs, <RETURNED> the number of sections in the help file.
  1148.  
  1149. tabs, <RETURNED> a pointer to an array of character pointers.These
  1150. character pointers point to the section names of the help file (the
  1151. tabs that appear along the bottom of a notebook). These section names
  1152. were created with malloc() and may be freed with free() when no longer
  1153. required. In addition the array of character pointers is also created
  1154. with malloc() and may also be freed with free().
  1155.  
  1156. topics, <RETURNED> a pointer to an array of character
  1157. pointers.These character pointers point to each section's corresponding
  1158. topic name in the help file. These topic names were created with malloc()
  1159. and may be freed with free() when no longer required. In addition
  1160. the array of character pointers is also created with malloc() and
  1161. may also be freed with free().
  1162.  
  1163.  Help_show
  1164.  
  1165. Synopsis
  1166.  
  1167. #include <help.h>
  1168. int Help_show(HelpID id, char *topic);
  1169.  
  1170. Description
  1171.  
  1172. Help_show instructs
  1173. the Help system to display a notebook at a particular topic.  If a
  1174. notebook for a particular file is already open, the Help system will
  1175. move the notebook to the foreground and update its contents to the
  1176. new topic.
  1177.  
  1178. id, Help id (returned by Help_initialize).
  1179.  
  1180. topic, the name of the topic to display.
  1181.  
  1182.  Help_terminate
  1183.  
  1184. Synopsis
  1185.  
  1186. #include <help.h>
  1187. int Help_terminate(HelpID id);
  1188.  
  1189. Description
  1190.  
  1191. Help_terminate
  1192. is used when your application has finished with a particular notebook
  1193. (or "connection" to the Help system).
  1194.  
  1195. id, Help id (returned by Help_initialize).
  1196.  
  1197. Error Codes
  1198.  
  1199. All help interface routines can return an error code (they all return
  1200. an integer value).
  1201.  
  1202. These codes are:
  1203.  
  1204. H_OK                    Success
  1205.  
  1206.  
  1207.  
  1208. /* Codes returned from Help system to interface routines */
  1209.  
  1210. PAD_NO_MEMORY           No memory to complete operation
  1211. PAD_NO_FILE             Help file not found
  1212. PAD_BAD_FILE            Bad help file
  1213. PAD_NO_TOPIC            Topic not found
  1214. PAD_BAD_CMD             Bad request command - contact QOS
  1215. PAD_SERVER_NO_MEM       Server out of memory
  1216. PAD_NO_CONNECT          Couldn't connect to Server
  1217.                         (XOpenDisplay failed)
  1218. PAD_BAD_VERSION         Mismatch between Help system and help
  1219.                         interface version numbers
  1220.  
  1221. /* Codes returned from all help interface routines */
  1222.  
  1223. H_BAD_ID                Help id is invalid
  1224. H_NO_MEMORY             No memory to complete operation
  1225.  
  1226.  
  1227.  
  1228. /* Codes returned by Help_get_sections
  1229. */
  1230.  
  1231. H_NO_FILE               Help file not found
  1232. H_BAD_FILE              Bad help file
  1233. H_NO_TOPIC              Topic not found
  1234. H_BAD_DVPFILE           Help .DVP file could not be found/read
  1235. H_FNAME_TOO_LONG        Help filename is too long
  1236.  
  1237. /* Codes returned by Help_show
  1238. */
  1239.  
  1240. H_TIMEOUT               Timeout occurred starting/sending message
  1241.                         to Help system
  1242.  
  1243. H_SEND_ERROR            Error occurred sending message to Help
  1244.                         system
  1245.  
  1246. H_RECEIVE_ERROR         Error occurred reading message from Help
  1247.                         system
  1248.  
  1249. H_START_ERROR           Couldn't start Help system - .DVP
  1250.                         couldn't be found, bad .DVP or
  1251.                         out of memory.
  1252.  
  1253. Example Program
  1254.  
  1255. The X11 Toolkit contains an example program, HELPCALL, that uses the
  1256. help interface routines. This program is contained in the \DVX\QDECK\HELP
  1257. directory.
  1258.  
  1259. HELPCALL illustrates how to use the help interface routines and may
  1260. be compiled using your C compiler.
  1261.  
  1262. Using DISPHELP
  1263.  
  1264. Included with DESQview/X is a standalone version of the help interface
  1265. routines--DISPHELP.EXE. This program may be used from
  1266. the DOS command line or within a .DVP file to display a help notebook.
  1267. (Application Manager uses this program to display all of the notebooks
  1268. in the Help group.)
  1269.  
  1270. DISPHELP.EXE is found in your DESQview/X directory
  1271. (normally \DVX).
  1272.  
  1273. Note that if an error occurs, DISPHELP displays the
  1274. error code returned by the help interface routines--see the "Error
  1275. Codes", section in this chapter, for a description of each error code.
  1276.  
  1277.  DISPHELP [-display displayname] [-pif
  1278. pifname] [-spawn] [-file filename]
  1279.  
  1280.  [-topic topicname] [-name "window name"] [-help]
  1281.  
  1282. DISPHELP accepts the following command line parameters:
  1283.  
  1284.  -display | -d displayname
  1285.  
  1286. displayname, the display the notebook is to appear on.
  1287. Default: your DISPLAY DOS variable, or :0 if not defined.
  1288.  
  1289.  -pif | -p pifname
  1290.  
  1291. pifname, the .DVP file to use to start the Help system.
  1292. Default: DVXHELP.DVP
  1293.  
  1294.  -spawn | -s
  1295.  
  1296. This switch, when specified, instructs the Help system to spawn a
  1297. completely separate notebook, even if an open notebook is already
  1298. displaying the same help file.
  1299.  
  1300.  -file | -f filename
  1301.  
  1302. filename, the help file to display. Default: DVXHELP.HLP
  1303.  
  1304.  -topic | -t topicname
  1305.  
  1306. topicname, the topic to display. Default: contents
  1307.  
  1308.  -name | -n "window name"
  1309.  
  1310. "window name", the name of the notebook's window.
  1311. Default: Help!
  1312.  
  1313.  -help | -h | -?
  1314.  
  1315. Displays a brief reminder of DISPHELP's parameters.
  1316.  
  1317.